Frontend WebHID Device Enumeration: Connected Device Discovery with JavaScript

WebHID API otključava potencijal web aplikacija za izravnu komunikaciju sa širokim rasponom Human Interface Devices (HID) koji su obično dostupni samo nativnim aplikacijama. Ovo otvara uzbudljive mogućnosti za stvaranje inovativnih web iskustava koja komuniciraju sa specijaliziranim hardverom kao što su kontroleri za igre, prilagođeni ulazni uređaji, znanstveni instrumenti i još mnogo toga. Ovaj sveobuhvatni vodič ulazi u osnovni koncept enumeracije uređaja, što je ključni prvi korak u uspostavljanju veze sa željenim HID uređajem.

What is the WebHID API?

WebHID API omogućuje web aplikacijama pristup Human Interface Devices. Ovi uređaji obuhvaćaju široku kategoriju, uključujući:

• Game Controllers: Joysticks, gamepads, racing wheels
• Input Devices: Keyboards, mice, trackballs
• Industrial Controls: Specialized control panels, sensor interfaces
• Scientific Instruments: Data acquisition devices, measurement tools
• Custom Hardware: Bespoke input devices created for specific purposes

Za razliku od starijih pregledničkih API-ja koji su nudili ograničenu HID podršku, WebHID API pruža izravan pristup HID uređajima, omogućujući programerima da stvaraju bogatije i interaktivnije web aplikacije. Zamislite kontrolu robotske ruke u udaljenom laboratoriju, manipuliranje 3D modelom pomoću prilagođenog ulaznog uređaja ili primanje podataka senzora izravno u web-baziranoj nadzornoj ploči - sve unutar preglednika.

Understanding HID Device Enumeration

Prije nego što možete komunicirati s HID uređajem, vaša web aplikacija mora otkriti koji su uređaji povezani sa sustavom korisnika. Ovaj se postupak naziva enumeracija uređaja. WebHID API pruža mehanizam za traženje pristupa određenim HID uređajima na temelju ID-a dobavljača (VID) i ID-a proizvoda (PID) ili pomoću šireg filtra.

Proces obično uključuje ove korake:

1. Requesting Device Access: Web aplikacija traži od korisnika da odabere HID uređaj pomoću navigator.hid.requestDevice().
2. Filtering Devices: Možete odrediti filtre za sužavanje popisa uređaja koji se prikazuju korisniku. Ovi se filtri temelje na VID-u i PID-u uređaja.
3. Handling Device Selection: Korisnik odabire uređaj s popisa.
4. Opening the Device: Aplikacija otvara vezu s odabranim uređajem.
5. Data Transfer: Nakon što se veza uspostavi, aplikacija može slati i primati podatke s uređaja.

Step-by-Step Guide to Device Enumeration

1. Requesting Device Access with Filters

Metoda navigator.hid.requestDevice() je ulazna točka za traženje pristupa HID uređajima. Prihvaća neobavezni argument `filters`, koji je niz objekata koji specificiraju VID i PID uređaja koje želite pronaći.

Evo primjera kako zatražiti pristup uređaju s određenim VID-om i PID-om:

async function requestHIDDevice() {
  try {
    const devices = await navigator.hid.requestDevice({
      filters: [
        {
          vendorId: 0x1234, // Replace with your device's Vendor ID
          productId: 0x5678 // Replace with your device's Product ID
        },
        // Add more filters for other devices if needed
      ]
    });

    if (devices.length > 0) {
      const device = devices[0]; // Use the first selected device
      console.log("HID Device Found:", device);
      // Open the device and start communication
      await openHIDDevice(device);
    } else {
      console.log("No HID device selected.");
    }
  } catch (error) {
    console.error("Error requesting HID device:", error);
  }
}

// Example usage (e.g., triggered by a button click):
document.getElementById('requestButton').addEventListener('click', requestHIDDevice);

Important Considerations:

• Vendor ID (VID) and Product ID (PID): Ovo su jedinstveni identifikatori dodijeljeni USB i Bluetooth uređajima. Morat ćete dobiti VID i PID ciljnog uređaja iz dokumentacije proizvođača ili pomoću sistemskih alata (npr. Upravitelj uređajima na sustavu Windows, Informacije o sustavu na macOS-u ili `lsusb` na Linuxu).
• User Consent: Metoda requestDevice() prikazuje prompt za dopuštenje kojim upravlja preglednik korisniku, omogućujući im da odaberu kojim HID uređajima žele odobriti pristup. Ovo je ključna sigurnosna mjera za sprječavanje zlonamjernih web stranica da pristupe osjetljivom hardveru bez pristanka korisnika.
• Multiple Filters: Možete uključiti više filtara u niz `filters` da biste zatražili pristup uređajima s različitim VID-ovima i PID-ovima. Ovo je korisno ako vaša aplikacija podržava više hardverskih konfiguracija.

2. Obtaining Device Information

Nakon što je korisnik odabrao uređaj, metoda requestDevice() vraća niz objekata HIDDevice. Svaki objekt HIDDevice sadrži informacije o uređaju, kao što su njegov VID, PID, usagePage, usage i zbirke. Ove informacije možete koristiti za daljnju identifikaciju i konfiguriranje uređaja.

async function openHIDDevice(device) {
  try {
    await device.open();
    console.log("HID Device Opened:", device.productName);

    // Listen for input reports
    device.addEventListener("inputreport", event => {
      const { data, reportId } = event;
      const uint8Array = new Uint8Array(data.buffer);
      console.log(`Received input report ${reportId}:`, uint8Array);
      // Process the input report data
    });

    device.addEventListener("disconnect", event => {
      console.log("HID Device Disconnected:", device.productName);
      // Handle device disconnection
    });

  } catch (error) {
    console.error("Error opening HID device:", error);
  }
}

Device Properties:

• vendorId: VID uređaja.
• productId: PID uređaja.
• productName: Naziv proizvoda čitljiv ljudima.
• collections: Niz objekata HIDCollectionInfo koji opisuju HID zbirke uređaja (izvješća, značajke, itd.). Ovo može biti vrlo složeno i potrebno je samo za složene uređaje.

3. Handling Device Connection and Disconnection

WebHID API pruža događaje za obavještavanje vaše aplikacije kada je uređaj povezan ili odspojen. Možete slušati događaje connect i disconnect na objektu navigator.hid.

navigator.hid.addEventListener("connect", event => {
  const device = event.device;
  console.log("HID Device Connected:", device);
  // Handle device connection (e.g., re-open the device)
});

navigator.hid.addEventListener("disconnect", event => {
  const device = event.device;
  console.log("HID Device Disconnected:", device);
  // Handle device disconnection (e.g., clean up resources)
});

Best Practices for Connection Management:

• Re-enumeration on Connect: Kada se uređaj poveže, često je dobra praksa ponovno nabrojati uređaje kako bi se osiguralo da vaša aplikacija ima ažurirani popis.
• Resource Cleanup on Disconnect: Kada se uređaj odspoji, oslobodite sve resurse povezane s njim (npr. zatvorite vezu s uređajem, uklonite slušatelje događaja).
• Error Handling: Implementirajte robusno rukovanje pogreškama kako biste graciozno upravljali situacijama u kojima se uređaj ne uspije povezati ili se neočekivano odspoji.

Advanced Device Filtering Techniques

Osim osnovnog VID i PID filtriranja, WebHID API nudi naprednije tehnike za ciljanje određenih uređaja. Ovo je osobito korisno kada imate posla s uređajima koji imaju više sučelja ili funkcionalnosti.

1. Filtering by Usage Page and Usage

HID uređaji organizirani su u *stranice upotrebe* i *upotrebe*, koje definiraju vrstu funkcionalnosti koju uređaj pruža. Na primjer, tipkovnica pripada stranici upotrebe "Generic Desktop" i ima upotrebu "Keyboard". Možete filtrirati uređaje na temelju njihove stranice upotrebe i upotrebe kako biste ciljali određene vrste uređaja.

async function requestSpecificKeyboard() {
  try {
    const devices = await navigator.hid.requestDevice({
      filters: [
        {
          usagePage: 0x01, // Generic Desktop Page
          usage: 0x06      // Keyboard Usage
        }
      ]
    });

    // ... (rest of the code to handle the device)
  } catch (error) {
    console.error("Error requesting HID device:", error);
  }
}

Finding Usage Page and Usage Values:

• HID Usage Tables: Službene HID tablice upotrebe (koje je objavio USB Implementers Forum) definiraju standardizirane stranice upotrebe i upotrebe za različite vrste uređaja.
• Device Documentation: Dokumentacija proizvođača uređaja može odrediti stranicu upotrebe i vrijednosti upotrebe za njihov uređaj.
• HID Report Descriptors: Za napredne scenarije možete analizirati HID deskriptor izvješća uređaja kako biste utvrdili njegove podržane stranice upotrebe i upotrebe.

2. Handling Multiple Interfaces

Neki HID uređaji izlažu više sučelja, svako sa svojim skupom funkcionalnosti. WebHID API tretira svako sučelje kao zaseban HID uređaj. Da biste pristupili određenom sučelju, možda ćete morati kombinirati VID/PID filtriranje sa stranicom upotrebe/filtriranjem upotrebe kako biste ciljali željeno sučelje.

Practical Examples and Use Cases

1. Building a Custom Game Controller Interface

Zamislite da gradite web-baziranu igru i želite podržati prilagođeni kontroler za igre. Možete koristiti WebHID API za izravno čitanje unosa s gumba kontrolera, joysticka i drugih kontrola. To vam omogućuje stvaranje vrlo responzivnog i impresivnog iskustva igranja.

2. Creating a Web-Based MIDI Controller

Glazbenici i audio inženjeri mogu imati koristi od web-baziranih MIDI kontrolera koji komuniciraju s digitalnim audio radnim stanicama (DAW) ili sintesajzerima. WebHID API omogućuje vam izgradnju prilagođenih MIDI kontrolera koji šalju i primaju MIDI poruke izravno u pregledniku.

3. Interacting with Scientific Instruments

Istraživači i znanstvenici mogu koristiti WebHID API za povezivanje sa znanstvenim instrumentima, kao što su uređaji za prikupljanje podataka, senzori i mjerni alati. To im omogućuje prikupljanje i analizu podataka izravno u web-baziranoj nadzornoj ploči ili alatu za analizu.

4. Accessibility Applications

WebHID pruža mogućnosti za stvaranje pomoćnih tehnologija. Na primjer, specijalizirani ulazni uređaji za korisnike s motoričkim oštećenjima mogu se integrirati izravno u web aplikacije, pružajući prilagođenija i pristupačnija iskustva. Globalni primjeri mogu uključivati integraciju specijaliziranih uređaja za praćenje očiju za navigaciju bez ruku ili prilagodljive nizove gumba za pristup s jednim prekidačem na različitim jezicima i metodama unosa.

Cross-Browser Compatibility and Security Considerations

1. Browser Support

WebHID API trenutno je podržan u preglednicima temeljenim na Chromiumu (Chrome, Edge, Opera) i u razvoju je za druge preglednike. Prije implementacije WebHID API-ja u svojoj aplikaciji, važno je provjeriti kompatibilnost preglednika i osigurati povratne mehanizme za preglednike koji ne podržavaju API.

2. Security Considerations

WebHID API dizajniran je imajući na umu sigurnost. Preglednik traži od korisnika dopuštenje prije nego što dopusti web aplikaciji pristup HID uređaju. To sprječava zlonamjerne web stranice da pristupe osjetljivom hardveru bez pristanka korisnika. Nadalje, WebHID API radi unutar sigurnosnog okruženja preglednika, ograničavajući pristup aplikacije sistemskim resursima.

• HTTPS Only: WebHID, kao i drugi moćni web API-ji, zahtijeva siguran kontekst (HTTPS) za rad.
• User Gestures: Zahtijevanje pristupa uređaju obično zahtijeva gestu korisnika (npr. klik gumba) kako bi se spriječili neželjeni zahtjevi za pristup.
• Permissions API: Permissions API se može koristiti za upite i upravljanje WebHID dopuštenjima.

Troubleshooting Common Issues

1. Device Not Found

Ako vaša aplikacija ne može pronaći HID uređaj, provjerite VID i PID. Provjerite odgovaraju li stvarnim identifikatorima uređaja. Također, provjerite je li uređaj ispravno povezan i prepoznat od strane operativnog sustava.

2. Permission Denied

Ako korisnik odbije dopuštenje za pristup HID uređaju, vaša aplikacija neće moći komunicirati s njim. Riješite ovaj scenarij graciozno prikazivanjem poruke korisniku i objašnjenjem zašto je potreban pristup. Razmislite o pružanju alternativnih načina za korisnika da komunicira s vašom aplikacijom.

3. Data Format Issues

HID uređaji često koriste prilagođene formate podataka za slanje i primanje podataka. Morat ćete razumjeti format podataka uređaja i implementirati odgovarajuću logiku parsiranja i serijalizacije u svojoj aplikaciji. Pogledajte dokumentaciju proizvođača uređaja za informacije o formatu podataka.

Conclusion

WebHID API osnažuje web programere da stvaraju inovativne i interaktivne web aplikacije koje komuniciraju izravno s Human Interface Devices. Razumijevanjem načela enumeracije uređaja, filtriranja i upravljanja vezama, možete otključati puni potencijal WebHID API-ja i stvoriti uvjerljiva korisnička iskustva. Prigrlite snagu WebHID-a da povežete web s fizičkim svijetom, potičući nove mogućnosti za kreativnost, produktivnost i pristupačnost diljem svijeta.

Further Resources

• WebHID API Specification
• WebHID API on Chrome Developers
• USB Implementers Forum (HID Information)